.TH llapi_fid_to_handle 3 "2022-11-08" "Lustre User API"
.SH NAME
llapi_fid_to_handle \- allocate an NFS handle for File Identifier
.SH SYNOPSIS
.nf
.B #include <lustre/lustreapi.h>
.PP
.BI "int llapi_fid_to_handle(struct file_handle **" handle ", struct lu_fid *" fid ");"
.fi
.SH DESCRIPTION
.PP
.BR llapi_fid_to_handle()
allocates an NFS file
.I handle
for the File Identifier given by
.I fid
for later use by
.BR open_by_handle_at (2).
This is similar to the
.BR name_to_handle_at (2)
function, and is useful for Lustre-specific tools and interfaces.  While the
.BR llapi_fid_to_handle (3)
function does not requre root access itself, the
.BR open_by_handle_at (2)
function
.B does
require root access since this bypasses all pathname-derived file access
permissions.
The memory allocated for
.I handle
and returned to the caller must be freed with
.IR free (2).
.SH RETURN VALUES
.LP
returns 0 on success or a negative errno on failure.
.SH ERRORS
.TP 15
.SM -ENOMEM
No memory was available for allocating
.IR handle .
.SH SEE ALSO
.BR free (3),
.BR llapi_fid_parse (3),
.BR llapi_fid2path (3),
.BR llapi_path2fid (3),
.BR lustreapi (7),
.BR name_to_handle (2)
.BR open_by_handle_at (2)
